Release 10.1A: OpenEdge Development:
Progress 4GL Handbook

Using the TABLE-HANDLE form

The third parameter form is unique to temp-tables, and this is the TABLE-HANDLE. You can use a TABLE-HANDLE to either pass or receive a dynamic temp-table, just as you would use the TABLE parameter form to pass a static temp-table.

To run a routine and pass a temp-table to or from the routine using a table handle, use this syntax:

RUN routine ( { [INPUT] | OUTPUT | INPUT-OUTPUT }     TABLE-HANDLE tt-handle ).

In the called routine, you define the parameter like this:

DEFINE { [INPUT] | OUTPUT | INPUT-OUTPUT }     PARAMETER TABLE-HANDLE tt-handle.

The tt-handle handle itself is exactly the same value you would pass as an ordinary HANDLE. However, the TABLE-HANDLE keyword tells Progress to pass not just the handle value but the entire definition and contents of the table as well, in exactly the same form as the TABLE parameter form uses.

You use the TABLE-HANDLE form to pass a dynamic temp-table and its description to another routine, or to receive a temp-table as a dynamic parameter from another routine, whether in the same session or on the other side of an AppServer connection. The corresponding parameter in the other routine can be a static TABLE or a dynamic TABLE-HANDLE.

The flexibility the TABLE-HANDLE form provides you is extremely valuable. For example, you might have procedures running on the server that represent business logic defined against static tables. On that side of the application, you can build static temp-tables that include database fields, calculated fields, and other elements. You can then pass the temp-table to the client using the TABLE parameter form, since you have a static temp-table definition locally.

On the client side of the application, you might have general purpose procedures to retrieve temp-tables from the server, perhaps to display data, allow updates, and do other client-side processing that might apply to many different tables received from the server. A general-purpose procedure that has no specific single temp-table definition can receive the table as a TABLE-HANDLE. It receives the entire table definition and data from the caller and can access it through the handle.

All combinations of TABLE and TABLE-HANDLE are valid. You can pass a static table using the TABLE form and receive it as a dynamic TABLE-HANDLE. You can pass a TABLE and receive it as a static TABLE of the same or compatible definition. You can pass a dynamic TABLE-HANDLE and receive it as a static TABLE, and you can pass a dynamic TABLE-HANDLE and receive it as a dynamic TABLE-HANDLE on the other side.

Use the TABLE-HANDLE form when the temp-table is not defined locally and you need to access it in a general way through its handle and buffer handle. Use the TABLE form when the temp-table is defined locally with a static DEFINE statement.

To review, Table 20–2 summarizes the possible combinations of temp-table parameter definitions in the routine making the call and the routine being called, along with their effects on the temp-table.

Table 20–2: Temp-table parameter definitions

Caller RUN statement form	Callee parameter form	Parameter type	Result
TABLE ttXYZ	TABLE ttXYZ	INPUT	Static temp-table ttXYZ in the caller is copied to the static definition of ttXYZ in the callee. The table definition is passed along with the data for validation only.
TABLE ttXYZ	TABLE-HANDLE hTT	INPUT	Definition and data of static temp-table ttXYZ in the caller are copied to the callee, which constructs a dynamic definition using handle hTT and loads the dynamic table with the data.
TABLE-HANDLE hTT	TABLE ttXYZ	INPUT	Definition and data of dynamic temp-table whose handle is hTT in the caller are copied to the callee, which receives the data into its static definition ttXYZ.
TABLE-HANDLE hTT	TABLE-HANDLE hTT	INPUT	Definition and data of dynamic temp-table whose handle is hTT in the caller are copied to the callee, which receives the definition and uses it to construct a dynamic temp-table using handle hTT, then loads the data into this dynamic table.
TABLE ttXYZ TABLE ttXYZ TABLE-HANDLE hTT TABLE-HANDLE hTT	TABLE ttXYZ TABLE-HANDLE hTT TABLE ttXYZ TABLE-HANDLE hTT	OUTPUT	All the same combinations are supported. Nothing is passed in to the callee. The definition of the table and its data are passed back in the same form from callee to caller when callee returns. For the OUTPUT TABLE form, the definition is used to validate compatible temp-table definitions; for the OUTPUT TABLE-HANDLE form, it is used to construct the temp-table in the caller.
TABLE ttXYZ TABLE ttXYZ TABLE-HANDLE hTT TABLE-HANDLE hTT	TABLE ttXYZ TABLE-HANDLE hTT TABLE ttXYZ TABLE-HANDLE hTT	INPUT-OUTPUT	Once again, the same combinations are supported. The table definition and data are passed in from caller to callee. Callee can make changes to the data in the table, which is returned by being copied back to the caller.
HANDLE	HANDLE	Any	Local only. Cannot be used on a remote call. The handle points to the temp-table instance in the caller (for INPUT and INPUT-OUTPUT modes) or the called routine (for OUTPUT mode). Only dynamic references to the temp-table are possible.